home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3dm / audio / alQueryValues.z / alQueryValues
Encoding:
Text File  |  2002-10-03  |  10.4 KB  |  265 lines
  1.  
  2.  
  3.  
  4. aaaallllQQQQuuuueeeerrrryyyyVVVVaaaalllluuuueeeessss((((3333ddddmmmm))))                                          aaaallllQQQQuuuueeeerrrryyyyVVVVaaaalllluuuueeeessss((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      alQueryValues - get the set of possible values for a parameter
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////aaaauuuuddddiiiioooo....hhhh>>>>
  13.  
  14.      iiiinnnntttt aaaallllQQQQuuuueeeerrrryyyyVVVVaaaalllluuuueeeessss((((iiiinnnntttt rrrreeeessss,,,, iiiinnnntttt ppppaaaarrrraaaammmm,,,, AAAALLLLvvvvaaaalllluuuueeee ****sssseeeetttt,,,, iiiinnnntttt sssseeeettttssssiiiizzzzeeee,,,,
  15.                             ALpv *quals, int qualsize);
  16.  
  17.  
  18. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRR
  19.      _r_e_s  expects the audio resource (see aaaallllRRRReeeessssoooouuuurrrrcccceeeessss((((3333ddddmmmm))))) for which you
  20.           desire the information.
  21.  
  22.      _p_a_r_a_m
  23.           expects the parameter whose values you desire. Not all parameters
  24.           support aaaallllQQQQuuuueeeerrrryyyyVVVVaaaalllluuuueeeessss((((3333ddddmmmm)))); see aaaallllPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) for which parameters
  25.           apply.
  26.  
  27.      _s_e_t  expects an array of ALvalues large enough to hold the results.  See
  28.           aaaallllPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) and aaaallllSSSSeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) for more information on ALvalues.
  29.  
  30.      _s_e_t_s_i_z_e
  31.           is the number of ALvalues in _s_e_t.
  32.  
  33.      _q_u_a_l_s
  34.           expects an array of ALpv structs called qqqquuuuaaaalllliiiiffffiiiieeeerrrrssss. These are used
  35.           to filter the results before putting them in the given _s_e_t.  See
  36.           aaaallllPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) and aaaallllSSSSeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) for more information on ALpv
  37.           structs.
  38.  
  39.      _q_u_a_l_s_i_z_e
  40.           is the number of ALpv structs in _q_u_a_l_s.
  41.  
  42. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  43.      aaaallllQQQQuuuueeeerrrryyyyVVVVaaaalllluuuueeeessss returns the set of possible values for a given parameter on
  44.      a given resource, optionally filtering through the results to see if they
  45.      meet certain qualifiers.
  46.  
  47.      aaaallllQQQQuuuueeeerrrryyyyVVVVaaaalllluuuueeeessss only applies to certain parameters whose values are
  48.      resources, enumerated values, or sets. See aaaallllPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) for information
  49.      on which parameters apply.
  50.  
  51.      Qualifiers only apply to parameters whose values are resources. If _q_u_a_l_s
  52.      is non-NULL and _q_u_a_l_s_i_z_e is non-zero, aaaallllQQQQuuuueeeerrrryyyyVVVVaaaalllluuuueeeessss will acquire the set
  53.      of potential values for _p_a_r_a_m, then filter through it, selecting only
  54.      those resources whose current values for the parameters in _q_u_a_l_s match
  55.      the corresponding values in _q_u_a_l_s.
  56.  
  57.      aaaallllQQQQuuuueeeerrrryyyyVVVVaaaalllluuuueeeessss will fill no more than _s_e_t_s_i_z_e elements in _s_e_t.  If _s_e_t_s_i_z_e
  58.      is 0, or _s_e_t is NULL, aaaallllQQQQuuuueeeerrrryyyyVVVVaaaalllluuuueeeessss will ignore _s_e_t. In any case, it will
  59.      return the number of possible values which meet the given qualifiers.
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. aaaallllQQQQuuuueeeerrrryyyyVVVVaaaalllluuuueeeessss((((3333ddddmmmm))))                                          aaaallllQQQQuuuueeeerrrryyyyVVVVaaaalllluuuueeeessss((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74. EEEEXXXXAAAAMMMMPPPPLLLLEEEE
  75.           #include <audio.h>
  76.  
  77.           /*
  78.            * A simple function to dump information about an
  79.            * AL resource.
  80.            */
  81.           void
  82.           dump_resources(ALvalue *x, int rv)
  83.           {
  84.               ALpv y[3];
  85.               char n[32];
  86.               int i;
  87.  
  88.               for (i = 0; i < rv; i++) {
  89.                y[0].param = AL_NAME;
  90.                y[0].value.ptr = n;
  91.                y[0].sizeIn = 32;
  92.                y[1].param = AL_RATE;
  93.                y[2].param = AL_TYPE;
  94.                alGetParams(x[i].i,y,3);
  95.                printf("found resource %d [%s] -- rate %lf, type %d\n",x[i].i, n,alFixedToDouble(y[1].value.ll), y[2].value.i);
  96.               }
  97.           }
  98.  
  99.           main()
  100.           {
  101.                ALvalue vals[32];
  102.                ALpv quals[16];
  103.                int rv;
  104.  
  105.                /*
  106.                 * alQueryValues can be used to count the number of
  107.                 * potential values for a parameter. We simply leave out
  108.                 * the sets. Here we ask how many different values
  109.                 * AL_DEFAULT_OUTPUT can have on our machine. This returns
  110.                 * the number of output devices on the system.
  111.                 */
  112.                if ((rv= alQueryValues(AL_SYSTEM,AL_DEFAULT_OUTPUT,0,0,0,0))>=0) {
  113.                printf("There are %d output devices on this system\n",rv);
  114.                }
  115.                else {
  116.                printf("alQueryValues failed: %s\n", alGetErrorString(oserror()));
  117.                exit(-1);
  118.                }
  119.  
  120.                /*
  121.                 * Now we find a device with a particular name. We could use
  122.                 * alQueryValues for this, using AL_NAME as a qualifier, e.g.
  123.                 *
  124.                 * quals[0].param = AL_NAME;
  125.                 * quals[0].value.ptr = "AnalogIn";
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. aaaallllQQQQuuuueeeerrrryyyyVVVVaaaalllluuuueeeessss((((3333ddddmmmm))))                                          aaaallllQQQQuuuueeeerrrryyyyVVVVaaaalllluuuueeeessss((((3333ddddmmmm))))
  137.  
  138.  
  139.  
  140.                 * quals[0].sizeIn = strlen(quals[0].value.ptr)+1;       // add 1 to count the NULL
  141.                 * if ((rv= alQueryValues(AL_SYSTEM,AL_DEVICES,vals,16,quals,1))>0) {
  142.                 *     printf("AnalogIn is resource %d\n",vals[0].i);
  143.                 * }
  144.                 *
  145.                 * ... but alGetResourceByName is easier.
  146.                 */
  147.                if (rv=alGetResourceByName(AL_SYSTEM, "AnalogIn", AL_DEVICE_TYPE)) {
  148.                printf("AnalogIn is resource %d\n",rv);
  149.                }
  150.  
  151.                /*
  152.                 * We look up the master clocks that this device can get to,
  153.                 * and find all whose types are AL_CRYSTAL_MCLK_TYPE.
  154.                 * Note that the device understands AL_MASTER_CLOCK even though
  155.                 * it's a clock-generator parameter -- parameters for interfaces
  156.                 * and clock-generators can be sent to the devices that use them.
  157.                 */
  158.                quals[0].param = AL_TYPE;
  159.                quals[0].value.i = AL_CRYSTAL_MCLK_TYPE;
  160.                if ((rv= alQueryValues(rv,AL_MASTER_CLOCK,vals,16,quals,1))>0) {
  161.                dump_resources(vals, rv);
  162.                }
  163.                if (rv < 0) {
  164.                printf("alQueryValues failed: %s\n", alGetErrorString(oserror()));
  165.                }
  166.           }
  167.  
  168.  
  169. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  170.      aaaallllQQQQuuuueeeerrrryyyyVVVVaaaalllluuuueeeessss always returns the number of possible values which meet the
  171.      qualifiers. If it finds no such possible values, it returns 0.  If the
  172.      call fails for other reasons, it returns -1.  In this case, the error
  173.      code retrieved by oooosssseeeerrrrrrrroooorrrr((((3333CCCC)))) will be one of:
  174.  
  175.      AAAALLLL____BBBBAAAADDDD____PPPPVVVVBBBBUUUUFFFFFFFFEEEERRRR
  176.           _q_u_a_l_s is invalid and _q_u_a_l_s_i_z_e is nonzero.
  177.  
  178.      AAAALLLL____BBBBAAAADDDD____BBBBUUUUFFFFFFFFEEEERRRRLLLLEEEENNNNGGGGTTTTHHHH
  179.           _q_u_a_l_s_i_z_e or _s_e_t_s_i_z_e is patently wrong (e.g. negative).
  180.  
  181.      AAAALLLL____BBBBAAAADDDD____DDDDEEEEVVVVIIIICCCCEEEE____AAAACCCCCCCCEEEESSSSSSSS
  182.           The audio system is inaccessible, either because it is not installed
  183.           on the system, or because it is incorrectly configured.
  184.  
  185.      AAAALLLL____BBBBAAAADDDD____RRRREEEESSSSOOOOUUUURRRRCCCCEEEE
  186.           The given resource _r_e_s does not exist.
  187.  
  188.      AAAALLLL____BBBBAAAADDDD____PPPPAAAARRRRAAAAMMMM
  189.           The given parameter _p_a_r_a_m is not supported by the given resource.
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. aaaallllQQQQuuuueeeerrrryyyyVVVVaaaalllluuuueeeessss((((3333ddddmmmm))))                                          aaaallllQQQQuuuueeeerrrryyyyVVVVaaaalllluuuueeeessss((((3333ddddmmmm))))
  203.  
  204.  
  205.  
  206. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  207.      oserror(3C), alParams(3dm), alGetParamInfo(3dm), alGetParams(3dm)
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.